home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / amiga / gui / prcgntn1.lha / Precognition / Precognition.doc < prev    next >
Text File  |  1993-01-01  |  11KB  |  292 lines
  1.                   Precognition: A step beyond Intuition
  2.  
  3.                         Release 1.02, January 1993
  4.  
  5.  
  6. Precognition is an interface builder program for Intuition that allows you
  7. to create attractive, 3D-style interfaces like Workbench 2.0, but under
  8. AmigaDos 1.3!
  9.  
  10. You use Precognition as if it were a structured drawing or paint program,
  11. i.e.  simply drag the desired gadgets on to the window, size and move them
  12. using the mouse.  When you're done, Precognition writes the C code to
  13. generate that window.
  14.  
  15. Unlike other Amiga interface-building programs, Precognition not only writes
  16. the declarations for the gadgets,  but also writes the code for opening and
  17. closing the window, and the event loop itself. (For any non-trivial
  18. interface, the event loop is usually the hardest part to write.)
  19.  
  20. Precognition is also a set of programming utilities for use with Intuition
  21. that make manipulating gadgets easier.  The code generated by the
  22. Precognition Interface builder relies heavily on the Precognition utilities.
  23.  
  24. FOR ADVANCED AMIGA PROGRAMMERS:  Unlike Intuition, Precognition is not a
  25. separate process on the Amiga.  It is merely a collection of functions which
  26. manipulate gadgets and windows.  i.e.  it's designed to extend Intuition,
  27. not replace it.
  28.  
  29.  
  30.                    Starting the Program from Workbench
  31.  
  32. Simply double-click the "Builder" icon.
  33.  
  34.  
  35.                     Starting the Program from the CLI
  36.  
  37. Type "Builder".
  38.  
  39.  
  40.                        Interlace vs. Non-Interlace
  41.  
  42. Precognition normally opens a screen with the same resolution as the
  43. Workbench screen.  You can force the screen to be (or not to be) interlaced
  44. via the tooltype "INTERLACE=".  Use "INTERLACE=YES" for interlace,
  45. "INTERLACE=NO" for non-interlace.
  46.  
  47.  
  48.                          The Application Window
  49.  
  50. Occupying most of the screen is a window titled "Application".  This is the
  51. window which you are designing.  You will add gadgets and graphics to this
  52. window by dragging them over from the "Gadgets" and "Graphics" windows.
  53.  
  54. To change the properties of the application window, select "Window
  55. Properties" from the "Edit" menu.  This will bring up the Window Properties
  56. requestor.  Using this requester, you can change the window title, the
  57. variable name, and the window gadgets (close, drag, front/back, resize).
  58.  
  59.  
  60.                             The Gadget Window
  61.  
  62. At the lower right side of the screen, there will be the "Gadgets" window
  63. which contains a set of buttons labelled with the different gadget types. To
  64. add one of these gadgets to the application window, simply move the mouse
  65. over the name of the gadget you wish,  press and hold the left mousebutton. 
  66. A gadget icon will be attached to your mouse pointer. Drag the gadget icon
  67. into the application window, and release the left mousebutton.
  68.  
  69.  
  70.                            The Graphics Window
  71.  
  72. To the left of the "Gadgets" window is the "Graphics" window which contains
  73. a set of buttons labelled with the different window graphics which can be
  74. added to the window.  Currently, there aren't very many graphics. You add
  75. these to the window the same way you add a gadget, i.e. drag them.
  76.  
  77.  
  78.                             Selecting Objects
  79.  
  80. To move, resize, or edit an object in the application window, you must first
  81. select it.  To select an object, move the mouse pointer over that object,
  82. and press and release the left mousebutton.  The object should now be
  83. displayed in inverse video.
  84.  
  85. Multiple objects can be selected at the same time by holding down either
  86. shift key while pressing the left mousebutton.
  87.  
  88. Objects can be selected by lasso-ing them.  Hold the left mousebutton down
  89. on an area of the window where there are no objects.  Now move the mouse.  A
  90. selection box will follow your mouse.  When you release the mouse, any and
  91. all objects completely within the selection box will be selected.
  92.  
  93.  
  94.                      Changing the Size of an Object
  95.  
  96. To change the size of an object, move the mouse pointer to the edge or
  97. corner of the object, press and hold the left mousebutton.  The pointer
  98. image should change to a triangular arrow.  Now drag the corner or edge of
  99. the object to its new size and release the left mousebutton.
  100.  
  101. You can cancel a size-change by pressing the right mousebutton before
  102. releasing the left mousebutton.
  103.  
  104. NOTE: The size of some objects cannot be changed, e.g. a CheckBox is a
  105. fixed size.  The size of some objects can only be changed along one axis.
  106. e.g. a StringGadget can get wider, but not taller.
  107.  
  108. If the pointer image becomes a hand you're not close enough to the edge of
  109. the object, or else this object does not size.
  110.  
  111. NOTE: You can only change the size of one object at a time. If multiple
  112. objects are selected, dragging the mouse will always move rather than
  113. resize.
  114.  
  115.  
  116.                              Moving Objects
  117.  
  118. You move objects on the application window the same way you move icons on
  119. the workbench screen.
  120.  
  121. To move one or more objects, first select the objects, and then move the
  122. mouse pointer to the center of one of the objects, press and hold the left
  123. mousebutton.  The pointer image will become a hand. Now drag the objects to
  124. their new location, and release the left mousebutton.
  125.  
  126. You can cancel a size-change by pressing by pressing the right mousebutton
  127. before releasing the left mousebutton.
  128.  
  129. If the pointer image becomes a triangular arrow instead of a hand you're too
  130. close to the edge of the object.
  131.  
  132.  
  133.                             Editing an Object
  134.  
  135. To edit the properties of an object, select the object, and then select
  136. "Object Properties" from the Edit menu.  This will bring up the object's
  137. property requestor.  This requestor will allow you to change the variable
  138. name for this object, its displayable title (if any), its size and location,
  139. and any other property which is applicable.
  140.  
  141.  
  142.                             Aligning Objects
  143.  
  144. You can align a set of objects by selecting those objects, and then
  145. selecting the appropriate option from the Align submenu of the Edit menu.
  146.  
  147.  
  148.                                 Grid Snap
  149.  
  150. You can also force alignment by turning on the Grid Snap.  Selecting 
  151. "Grid Snap ╗ Grid Controls" from the Edit menu will display the Grid Snap
  152. requestor, which allows you to set the grid snap parameters.
  153.  
  154. There are actually two separate grid snaps:
  155.  
  156.    "Location Snap" will force the upper-left corner of an object to be
  157.    on a grid when you drag it.
  158.  
  159.    "Size Snap" will force the corner or edge of an object to be on a
  160.    grid when you size it.
  161.  
  162.  
  163.                             Deleting Objects
  164.  
  165. To delete one or more objects, select those objects, and then select Delete
  166. from the Edit menu.
  167.  
  168. WARNING: Once you delete an object, its gone for good.
  169.  
  170. Sooner or later I'll get around to adding Cut/Copy/Paste instead of Delete. 
  171. (Sigh. So many improvements, so little time...)
  172.  
  173.  
  174.                              Generating Code
  175.  
  176. To generate code for the application window, select "Write Code" from the
  177. "Project" menu.  This will bring up a file requester for the C source code.
  178. Type or select a filename, and press the "OK" gadget.  Precognition will
  179. then write the C source code declarations for your window.
  180.  
  181. Precognition generates a 'struct' which defines your window, and 6
  182. functions.  (Where "<window-name>" is the name you chose for the
  183. window.)
  184.  
  185.    <window-name>_Init         -- initializes all the objects in the 
  186.                                  window you designed.
  187.  
  188.    <window-name>_CleanUp      -- releases all the memory allocated to
  189.                                  the objects in the window.
  190.  
  191.    <window-name>_Respond      -- Code which responds to a single 
  192.                               -- IntuiMessage 'event' from Intuition.
  193.  
  194.    <window-name>_EventLoop    -- initializes and opens the window, 
  195.                                  gets events from Intuition, calls
  196.                                  <window-name>_Respond() until 
  197.                                  global variable 'Done' is set to
  198.                                  TRUE. calls <window-name>_CleanUp().                                 
  199.    
  200.    main                       -- main program.  Opens libraries, calls
  201.                                  <window-name>_EventLoop, GracefulExit.
  202.  
  203.    GracefulExit               -- closes libraries.
  204.    
  205.  
  206. The generated code should be compileable and linkable (with
  207. Precognition.lib) as generated.
  208.  
  209.                        About the Generated Code...
  210.  
  211. Precognition does not generate standard Intuition variables and function
  212. calls.  (This is because 1.3 Intuition does not have built-in 3-D buttons
  213. and scrolling lists and such)  Instead Precognition generates code which use
  214. special Precognition data types and functions.  In order for your program to
  215. use these functions, you must link your code with the file
  216. "Precognition.lib", which contains all the special Precognition calls.
  217.  
  218. Throughout the code you will say lines which say "/* YOUR CODE HERE */".
  219. These are the areas which you the programmer must fill in.  Precognition
  220. inserts these statements to indicate that a User-interface event has
  221. occurred, and you should take the appropriate action.  EXAMPLE: If you
  222. create a window with an "OK" button, Precognition will generate the
  223. following statements:
  224.  
  225.       if (Respond( (Interactor*) &OK_button, &event) & CHANGED_STATE)
  226.       {  /* OK_button was hit. */
  227.          ; /* YOUR CODE HERE */
  228.       }
  229.  
  230. You, the programmer, need to supply the code to take the appropriate action
  231. when the OK button is pressed.  (Precognition doesn't know what you want to
  232. happen when "OK" is hit.)
  233.  
  234. The code as written should be compilable and linkable, although it
  235. won't do anything except have pretty buttons until you fill in the
  236. /* YOUR CODE HERE */ areas.  
  237.  
  238.  
  239.                   Terminating the Event Loop
  240.       
  241. The generated event loop runs until global variable 'Done' is set to
  242. TRUE.  As generated, the only event in the code which does this is 
  243. hitting the window's closebox.  If you want to have other actions
  244. exit the window (e.g. an "OK" button), you need to add a line to set 
  245. 'Done' to TRUE in the event code for the OK button.  e.g.
  246.  
  247.       if (Respond( (Interactor*) &OK_button, &event) & CHANGED_STATE)
  248.       {  /* OK_button was hit. */
  249.          Done = TRUE; /* <-- YOUR CODE HERE */
  250.       }
  251.  
  252. NOTE: If you do not include a closebox on your window, then the event loop
  253. is infinite until you modify the code.
  254.  
  255.  
  256. Precognition uses an OO paradigm via pointers-to-functions, which allows
  257. the same function to do different things to different objects
  258. ("polymorphism"). e.g.
  259.  
  260.    SetLocation(&BoolGadget, 10, 10 );
  261.  
  262. sets the location of a boolean gadget to be 10,10 in its window, while
  263.  
  264.    SetLocation( &pcgWindow, 10, 10 );
  265.  
  266. sets the location of the window to be 10, 10 on its screen.
  267.  
  268. All header files have an 'object genealogy' at the top of the file which
  269. describes the parents of the object.  e.g.
  270.  
  271.    PObject<GraphicObject<OutlineBox
  272.  
  273. Says that object class OutlineBox is a descendent of class GraphicObject,
  274. which is a descendent of class PObject.  Any function you can call on an
  275. PObject or a GraphicObject, you can call on an OutlineBox.  To find out
  276. what operations an object supports, look at the prototypes in the objects
  277. header files, and all parent header files.
  278.  
  279.  
  280.                             About the Author
  281.  
  282. You can get in touch with me on USENET via:
  283.  
  284.    Lee_Robert_Willis@cup.portal.com
  285.  
  286. Or, when all else fails, you can reach me via U.S mail at:
  287.  
  288.       Lee Willis
  289.       590 Eleanora Dr.
  290.       Cuyagoga Falls, Ohio USA
  291.       44223-2732
  292.